docs(governance): start standalone OpenSpec change for doc lifecycle traceability - #126

…c lifecycle

Context:\nPR #113 confirmed that cross-project documentation governance philosophy should be handled in a dedicated follow-up change instead of being mixed into runtime rebase work.\n\nWhat this commit includes:\n- creates OpenSpec change \n- adds proposal defining scoped governance objectives: aggregation entry, frontmatter contract, active/archive indexing, and machine-checkable checkpoints\n- adds technical design covering decisions, risks, migration strategy, and non-goals\n- adds capability specs:\n  - new capability: \n  - modified capability: \n- adds implementation task breakdown (12 tasks) to drive follow-up execution in small verifiable steps\n\nRationale:\nThis commit intentionally starts with governance contracts and execution plan artifacts only, so the follow-up implementation PR can proceed under explicit OpenSpec requirements with traceable acceptance criteria.\n\nVerification:\n- openspec status --change enhance-doc-governance-traceability --json\n- openspec instructions apply --change enhance-doc-governance-traceability --json\n- openspec validate --changes enhance-doc-governance-traceability

Context:
A follow-up review highlighted that the standalone governance change mentioned automated checkpoints but did not explicitly encode the “SOP skillization” requirement raised in PR #113.

Updates in this commit:
- proposal: adds explicit scope for skillizing governance lifecycle stages (kickoff/execution/completion/verification)
- design: adds a dedicated decision for checkpoint-to-skill mapping and skill-based governance execution semantics
- specs:
  - documentation-lifecycle-traceability: adds requirement that key SOP stages MUST be represented by callable skills
  - design-reconstructability-governance: adds requirement to maintain auditable checkpoint-skill mappings
- tasks: adds a dedicated SOP skillization workstream and renumbers pilot tasks accordingly

Verification:
- openspec validate --changes enhance-doc-governance-traceability
- openspec status --change enhance-doc-governance-traceability --json

…ll execution model

Context:
The governance follow-up needed to explicitly cover directory unification, document-type lifecycle control, OpenSpec/default collaboration semantics, TODO fallback semantics, and reusable skill-based execution so documentation does not drift into ad-hoc patterns.

What changed:
- Added unified documentation management model:
  - docs/governance/Documentation_Management_Model.md
  - defines directory taxonomy, document-type placement rules, lifecycle dependency chain,
    OpenSpec default mode, TODO fallback mode, frontmatter contract, checkpoint-skill mapping,
    and effectiveness criteria
- Added feature aggregation layer:
  - docs/features/README.md
  - docs/features/enhance-doc-governance-traceability.md
  - docs/features/archive/.gitkeep
- Added unified governance skill:
  - .codex/skills/documentation-lifecycle-governance/SKILL.md
- Updated standards and navigation docs to align with the new model:
  - AGENTS.md
  - docs/agent_rules.md
  - docs/README.md
  - docs/guides/Development_Constraints.md
  - docs/guides/Documentation_First_Development_SOP.md
  - docs/design/Design_Reconstructability_Traceability_Matrix.md
  - docs/todos/README.md
- Expanded OpenSpec change contract to include:
  - directory taxonomy unification
  - explicit OpenSpec-vs-fallback collaboration
  - lifecycle dependency requirement
  - status single-source-of-truth requirement

OpenSpec artifacts updated:
- openspec/changes/enhance-doc-governance-traceability/proposal.md
- openspec/changes/enhance-doc-governance-traceability/design.md
- openspec/changes/enhance-doc-governance-traceability/specs/documentation-lifecycle-traceability/spec.md
- openspec/changes/enhance-doc-governance-traceability/specs/design-reconstructability-governance/spec.md
- openspec/changes/enhance-doc-governance-traceability/tasks.md

Verification:
- openspec validate --changes enhance-doc-governance-traceability
- openspec status --change enhance-doc-governance-traceability --json

…workflow skills

Introduce two explicit governance skills to separate concerns and align with PR feedback:
- add documentation-management for taxonomy/path/frontmatter/archive controls
- add documentation-workflow for lifecycle checkpoints, OpenSpec-default flow, TODO fallback, and evidence sync
- keep documentation-lifecycle-governance as a compatibility wrapper that delegates to the two new skills

Update governance standards and OpenSpec artifacts to codify the two-skill requirement and checkpoint mapping:
- AGENTS + guides + governance model + agent rules now reference dual-skill execution
- feature aggregation anchor updated to both skills plus legacy wrapper
- proposal/design/spec/tasks now require at least two governance skills and reflect the new mapping contract

Validation evidence:
- openspec validate --changes enhance-doc-governance-traceability
- openspec status --change enhance-doc-governance-traceability --json

…kill

Apply governance model refinement from review feedback:
- remove  as a separate compatibility skill
- merge lifecycle-governance responsibilities into
- rename  to  to reflect that the second skill governs delivery workflow rather than document-only operations

Synchronize standards and OpenSpec artifacts to the new two-skill contract:
- update AGENTS, constraints, SOP, agent rules, and feature anchors
- update checkpoint-to-skill mapping in Documentation_Management_Model
- update proposal/design/spec/tasks to require  +

Validation evidence:
- openspec validate --changes enhance-doc-governance-traceability
- openspec status --change enhance-doc-governance-traceability --json

Refine the two-skill governance model after alignment review against the documentation-first SOP and PR discussion context.

Key updates:
- strengthen development-workflow trigger conditions and scope boundaries
- encode mandatory SOP kickoff gates in the workflow skill (design-first, gap analysis, TODO before implementation)
- tighten execution-sync/verification/completion steps to mirror SOP and DoD checkpoints
- make frontmatter contract mandatory in Documentation_Management_Model
- fix OpenSpec spec links in feature aggregation entry to repository-root paths

Validation evidence:
- openspec validate --changes enhance-doc-governance-traceability
- openspec status --change enhance-doc-governance-traceability --json

…vs-openspec boundary

Resolve remaining governance review gaps and clarify source-of-truth boundaries.

Changes in skills:
- development-workflow now uses mode-aware execution-sync and verification checkpoints
- development-workflow now defines mode-aware completion behavior for OpenSpec and TODO fallback
- documentation-management now defines mode-aware metadata keys for OpenSpec and TODO fallback

Changes in governance docs:
- Documentation_Management_Model now includes design in doc_kind metadata contract
- Documentation_Management_Model now declares TODO fallback exception for change_ids before migration
- Documentation_Management_Model now defines source-of-truth boundary: docs as canonical full record, OpenSpec as execution trace
- Documentation_First_Development_SOP now explicitly states docs are canonical and OpenSpec outcomes must be written back to docs

Validation evidence:
- openspec validate --changes enhance-doc-governance-traceability
- openspec status --change enhance-doc-governance-traceability --json

…Spec slicing

Align governance workflow with the clarified execution model:
- analysis/gap + master TODO backlog come first for bug/feature/refactor
- docs updates are treated as OpenSpec inputs, not post-hoc artifacts
- OpenSpec is used as slice-level execution tracking and can span multiple change-ids for one large initiative
- docs remain the canonical full record; openspec remains process trace

Updated standards and skills:
- SOP restructured to analysis -> master TODO -> docs update -> OpenSpec slicing -> execution -> verification -> archive
- Development_Constraints and AGENTS sequence aligned to master-TODO-first slicing workflow
- development-workflow skill now enforces mode-aware slice execution against master TODO
- documentation-management skill now requires planning-to-execution mapping for TODO subset coverage
- Documentation_Management_Model now documents slicing policy and optional todo_ids/mode metadata

OpenSpec contract updates:
- proposal/design updated with source-of-truth boundary and multi-change slicing decisions
- specs updated with mandatory requirements for analysis-first input and TODO-to-change slice mapping
- tasks expanded with boundary/slicing alignment and mapping-check coverage

Validation evidence:
- openspec validate --changes enhance-doc-governance-traceability
- openspec status --change enhance-doc-governance-traceability --json

Address new PR #126 review feedback by making TODO fallback metadata and path rules explicit and consistent across skill, SOP, governance model, and OpenSpec design docs.

Key updates:

- Require topic_slug alongside mode: todo_fallback in development-workflow skill fallback instructions.

- Mirror the same requirement in Documentation-First SOP fallback sequence.

- Make Documentation Management Model feature-doc placement mode-aware (OpenSpec by change-id, fallback by topic-slug) while preserving single-source status semantics.

- Standardize OpenSpec mode frontmatter contract to change_ids and define fallback-required fields plus migration expectation.

Rationale: reviewers flagged ambiguity between change-id and topic-slug paths plus mixed feature_ids/change_ids language. This commit removes ambiguity and ensures deterministic governance behavior in both OpenSpec and fallback workflows.

…rkflow

Align governance skills and contracts with latest PR feedback by treating CI as a full governance gate (not skill-only) and by promoting evidence/review records to first-class artifacts.

Key changes:

- Fix lifecycle dependency order to match SOP: standards -> design -> gap -> master TODO -> feature aggregation -> execution -> evidence -> review/merge gate -> archive.

- Standardize proposal frontmatter wording to change_ids and remove remaining schema ambiguity in the proposal layer.

- Extend development-workflow skill with required Evidence block schema, review-merge-gate checkpoint, and explicit CI scope checks (metadata, links, evidence completeness, TODO/change mapping, checkpoint mapping).

- Extend documentation-management skill with mailbox classification (temporary_coordination vs audit_evidence), retention rules, and CI-scope guidance beyond skill-file checks.

- Update governance model with truth-layer semantics (normative/operational/evidence), mode-aware workflow steps, mailbox metadata contract, review-merge-gate mapping, and expanded CI minimum checks.

- Update OpenSpec specs to encode the same lifecycle order and CI-scope requirements, including review/merge gate evidence retention.

- Backfill the active feature aggregation doc with structured evidence sections (commands/results/behavior/risk/rollback/review links).

Rationale: this removes remaining SOP-model mismatches, resolves new review comments, and prevents future drift where governance checks are reduced to skill-presence-only validation.

…rategy

Promote evidence truth from guideline language to enforceable repository contract by adding a dedicated strategy document, wiring an initial structural CI gate, and synchronizing governance/SOP/skills/OpenSpec references.

Key changes:

- Added docs/guides/Evidence_Truth_Implementation_Strategy.md with phased implementation plan (structural gate -> semantic checks -> merge policy coupling).

- Added scripts/ci/check_governance_evidence_truth.sh to enforce active feature-doc evidence structure, mode-aware frontmatter keys, artifact path resolvability, and review-link presence.

- Wired the new gate into .github/workflows/ci-gate.yml as governance-evidence-truth job.

- Updated governance standards and execution guides (AGENTS, Development_Constraints, Documentation_First_Development_SOP, docs/README, docs/features/README, docs/agent_rules) to require and reference the evidence-truth contract and gate command.

- Updated OpenSpec proposal/spec/tasks to encode the new evidence-truth strategy and CI gate command as part of change scope.

- Refreshed feature aggregation evidence section to include the new gate command result.

Rationale: PR feedback requested evidence truth to be concretely operationalized. This commit provides deterministic, auditable, and automatable enforcement rather than relying on narrative review discipline.

…y into documentation-management skill

Refine governance guidance after review feedback to avoid over-specifying implementation commands in AGENTS and to clarify skill ownership boundaries for evidence-truth governance.

Key changes:

- AGENTS now references governance contracts ( and ) instead of directly naming a concrete script command.

- documentation-management skill adds an authoritative-inputs section and explicitly states it is the single execution entry for both governance model and evidence-truth strategy, avoiding unnecessary evidence-only skill splitting.

Rationale: AGENTS should remain stable policy guidance, while concrete implementation details belong to skills/guides/CI. Evidence-truth and documentation governance currently share one cohesive responsibility domain, so merging into documentation-management is simpler and less error-prone than creating a third skill.

… references

Apply two governance alignment updates requested in review follow-up.

Key changes:

- AGENTS.md now keeps only high-level documentation-first policy and removes explicit references to Documentation_Management_Model, Evidence_Truth_Implementation_Strategy, and concrete skill/script declarations.

- Added mirrored governance skills to .claude and .gemini skill catalogs:

  - documentation-management

  - development-workflow

- Mirrored files are copied from the current .codex skill definitions to keep agent runtimes behaviorally consistent across Codex, Claude, and Gemini work modes.

Rationale: AGENTS should remain policy-oriented while concrete execution contracts live in skills and CI gates; multi-agent directories must stay synchronized to avoid divergent workflow behavior.

Address the latest unresolved PR review threads by aligning SOP checkpoints and hardening the governance evidence gate behavior.

Key changes:

- Added  to mandatory checkpoint list in Documentation_First_Development_SOP so SOP matches governance model and development-workflow skill.

- Hardened scripts/ci/check_governance_evidence_truth.sh artifact-path validation: every extracted OpenSpec artifact path is now validated, eliminating silent skips for malformed relative entries (e.g., specs/... without repo-root prefix).

- Scoped evidence enforcement to active feature docs by reading frontmatter status; non-active docs are skipped to avoid draft-stage false positives.

- Added frontmatter parsing helpers and change_ids validation that supports both single-line and multiline YAML list formats, reducing formatting-related false negatives in future rollout phases.

Rationale: this resolves active review findings while keeping the gate deterministic and compatible with documented lifecycle semantics.